home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 October: Mac OS SDK / Dev.CD Oct 96 SDK / Dev.CD Oct 96 SDK2.toast / Development Kits (Disc 2) / OpenDoc / Developer Documentation / Recipes, Tech Notes & Articles / Tech Notes / Utilities Documentation / SEUtils < prev    next >
Encoding:
Text File  |  1995-11-06  |  4.2 KB  |  88 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Utilities Documentation
  2.  
  3.  
  4. Semantic Events Utilities
  5. 10/31/95
  6.  
  7. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  8. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  9. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  10.  
  11. Introduction
  12.  
  13. This C++ class implements a simple hash table that efficiently handles keys and values of 4 and 8 bytes as well as handling other sizes.
  14.  
  15. Routines (SEUtils.cpp)
  16.  
  17. ODBoolean MissingParams(const AppleEvent* message);
  18.  
  19. Checks for the presence of a parameters that haven't yet been retrieved from the Apple event. Uses the method of getting the attribute keyMissedKeywordAttr.
  20.  
  21. OSErr DecodeOrdinal(AEDesc ordData, long count, long* index,
  22.                     Boolean* allFlag, Boolean* zeroFlag);
  23.  
  24. This routine was lifted from the sample code for the app Scriptable Text Editor. Here's the description from the source file.
  25.  
  26.  This routine is used whenever an element is specified by an absolute position
  27.   within a sequence of elements - such as "word 3 of window 'johnson'", "any line
  28.   of item 17 of window 'Kelvin'", etc.  The data specifying the position can be
  29.   a positive integer (which just means the actual position of the element in the
  30.   sequence: 1 for the first element, 2 for the second, etc.), a negative integer
  31.   (which indicates position relative to the last element of the sequence: -1 is
  32.   the last element, -2 the next to last, etc.), or a descriptor of typeAbsoluteOrdinal:
  33.   kAEFirst, kAELast, kAEMiddle, kAEAny, or kAEAll.  
  34.   
  35.   DecodeOrdinal takes the data specifying the position, and a count of all the elements
  36.   in the sequence under consideration, and returns (whenever possible) a positive integer
  37.   (in the return VAR index) representing the actual position of the element in the sequence 
  38.   (1 for first, 2 for second, etc.).  It also returns flags indicating (a) whether the 
  39.   ordinal was kAEAll and (b) whether the count was 0; both of these are conditions that 
  40.   many calling routines will have to special-case.  In the case of kAEAll, the return VAR 
  41.   index is set to the count; in the case of count = 0, the return VAR index is set to 0.
  42.   
  43.   There are a few error conditions:  (a) count < 0; (b) bad ordData (not an integer, and
  44.   not one of the five defined absolute ordinal specifiers).  **CHECK - should "integer ordData
  45.   out of range" (for example, an integer > count, or < -count, or = 0) be an error,
  46.   or should we allow that so that people can talk about "the hypothetical element
  47.   beyond the last", or whatever?  For now, let's make that a non-error.
  48.   
  49.   INPUTS:    ordData        a descriptor that specifies an ordinal - either
  50.                           an integer (positive or negative) or something
  51.                         of typeAbsoluteOrdinal
  52.             count        the total number of elements in the group involved
  53.                         (number of windows, number or chars, or whatever)
  54.             index        return VAR for the actual position being described
  55.             allFlag        return VAR: TRUE if the ordData was kAEAll, FALSE o.w.
  56.             zeroFlag    return VAR: TRUE if the count was zero (for many
  57.                         calling routines this is an error condition), FALSE o.w.
  58.   OUTPUTS:    error code (noErr if none)
  59.  
  60. ODSLong GetSLongAttr(AppleEvent* ae, AEKeyword keyword);
  61.  
  62. Retrieves a signed long attribute from an Apple event.
  63.  
  64. ODSLong GetSLongAttrOD(ODAppleEvent* ae, AEKeyword keyword);
  65.  
  66. Retrieves a signed long attribute from an ODAppleEvent.
  67.  
  68. void ThrowIfCantCoerce( AEDesc* data, DescType desiredType ) ;
  69.  
  70. Performs an in-place coercion of the AEDesc and calls THROW on any error returned from AECoerceDesc. 
  71.  
  72. void ThrowIfNotAbsent( OSErr err ) ;
  73.  
  74. THROWS err if err is not equal to noErr or errAEDescNotFound.
  75.  
  76. ODSLong CountEmbeddedParts(Environment* ev, ODPart* prt);
  77.  
  78. Uses the embedded frames iterator to count the number of embedded parts. If the prt is the shell, 1 is returned.
  79.  
  80. void UpdateUserToken(Environment* ev, ODNameResolver* resolver,
  81.                         ODOSLToken* odToken, AEDesc* desc);
  82.  
  83. Updates the user token in odToken with data in desc. desc is disposed.
  84.  
  85. OSErr ODDisposeAppleEvent( AppleEvent* aevt );
  86.  
  87. Call this to dispose an AppleEvent that was created by copying (e.g., using ODDescToAEDesc). Does a double-dispose of the AppleEvent. (If the AppleEvent is a copy of a send-to-self event, the AppleEvent cannot be disposed with a single call to AEDisposeDesc.)
  88.